Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

Changing Sequence-Decompression Parameters

This section discusses the functions that enable your application to manipulate the parameters that control sequence decompression and to get information about memory that the decompressor has allocated. Your application establishes the default value for most of these parameters with the DecompressSequenceBegin function (described on DecompressSequenceBegin ). Some of these functions deal with parameter values that cannot be set when starting a sequence.

You can determine the buffers used by a decompressor component when it decompresses a sequence. Use the GetDSequenceImageBuffer function to determine the location of the image buffer. Use the GetDSequenceScreenBuffer function to determine the location of the screen buffer.

You can control a number of the parameters that affect a decompression operation (note that changing these parameters may temporarily affect performance). Use the SetDSequenceAccuracy function to control the accuracy of the decompression. Use the SetDSequenceDataProc function to assign a data-loading function to the operation. Use the SetDSequenceMask function to set the clipping region for the resulting image. You can establish a blend matte for the operation by calling the SetDSequenceMatte function. You can alter the spatial characteristics of the resulting image by calling the SetDSequenceMatrix function. Your application can establish the size and location of the operation's source rectangle by calling the SetDSequenceSrcRect function. Finally, you can set the transfer mode used by the decompressor when it draws to the screen by calling the SetDSequenceTransferMode function.

SetDSequenceTransferMode

The SetDSequenceTransferMode function sets the mode used when drawing the decompressed image.

pascal OSErr SetDSequenceTransferMode (ImageSequence seqID,
                                         short mode,
                                         const RGBColor *opColor);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
mode
Specifies the transfer mode used when drawing the decompressed image. The Image Compression Manager supports the same transfer modes supported by QuickDraw's CopyBits routine (described in Inside Macintosh: Imaging ).
opColor
Contains a pointer to the color for use in addPin , subPin , blend , and transparent operations. The Image Compression Manager passes this color to QuickDraw as appropriate. If nil , the opcolor is left unchanged.

DESCRIPTION

The Image Compression Manager supports the same transfer modes supported by QuickDraw's CopyBits routine. The new mode takes effect with the next frame in the sequence. For any given sequence, the default opcolor is 50 percent gray and the default mode is ditherCopy .

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

SEE ALSO

You set the default transfer mode for a sequence with the mode parameter to the DecompressSequenceBegin function.

SetDSequenceSrcRect

The SetDSequenceSrcRect function defines the portion of the image to decompress.

pascal OSErr SetDSequenceSrcRect (ImageSequence seqID,
                                          const Rect *srcRect);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
srcRect
Contains a pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height) , where desc refers to the image description structure you supply to the DecompressSequenceBegin function. If the srcRect parameter is nil , the rectangle is set to the rectangle structure of the image description structure.

DESCRIPTION

The decompressor acts on that portion of the compressed image that lies within this rectangle. The new source rectangle takes effect with the next frame in the sequence.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

SEE ALSO

You set the default source rectangle for a sequence with the srcRect parameter to the DecompressSequenceBegin function.

SetDSequenceMatrix

The SetDSequenceMatrix function assigns a mapping matrix to the sequence.

pascal OSErr SetDSequenceMatrix (ImageSequence seqID,
                                          MatrixRecordPtr matrix);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
matrix
Points to a matrix structure that specifies how to transform the image during decompression. You can use the matrix structure to translate or scale the image during decompression. To set the matrix to identity, pass nil in this parameter. See the chapter "Movie Toolbox" in this book for more information about matrix operations.

DESCRIPTION

The decompressor uses the matrix to create special effects with the decompressed image, such as translating or scaling the image. The new matrix takes effect with the next frame in the sequence.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

SEE ALSO

You set the default matrix for a sequence with the matrix parameter to the DecompressSequenceBegin function.

SetDSequenceMask

The SetDSequenceMask function assigns a clipping region to the sequence.

pascal OSErr SetDSequenceMask (ImageSequence seqID,
                                         RgnHandle mask);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
mask
Contains a handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you want to stop masking, set this parameter to nil .

DESCRIPTION

The decompressor draws only that portion of the decompressed image that lies within the specified clipping region. The new region takes effect with the next frame in the sequence. You should not dispose of this region until the Image Compression Manager is finished with the sequence, or until you set the mask either to nil or to a different region by calling the SetDSequenceMask function again.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

Memory Manager errors

SEE ALSO

You set the default clipping region for a sequence with the mask parameter to the DecompressSequenceBegin function.

SetDSequenceMatte

The SetDSequenceMatte function assigns a blend matte to the sequence.

pascal OSErr SetDSequenceMatte (ImageSequence seqID,
                                         PixMapHandle matte,
                                         const Rect *matteRect);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
matte
Contains a handle to a pixel map that contains a blend matte. You can use the blend matte to cause the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth--the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If you want to turn off the blend matte, set this parameter to nil .
matteRect
Contains a pointer to the boundary rectangle for the matte. The decompressor uses only that portion of the matte that lies within the specified rectangle. This rectangle must be the same size as the source rectangle you specify with the SetDSequenceSrcRect function (described on SetDSequenceSrcRect ) or with the srcRect parameter to the DecompressSequenceBegin function. To specify the matte pixel map bounds, pass nil in this parameter.

DESCRIPTION

The decompressor uses the matte to blend the decompressed image into the destination pixel map. The new matte and matte boundary rectangle take effect with the next frame in the sequence. You should not dispose of the matte until the Image Compression Manager is finished with the sequence.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

Memory Manager errors

SetDSequenceAccuracy

The SetDSequenceAccuracy function adjusts the decompression accuracy for the current sequence.

pascal OSErr SetDSequenceAccuracy (ImageSequence seqID,
                                         CodecQ accuracy);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
accuracy
Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See "Compression Quality Constants," , for available values.

DESCRIPTION

The accuracy parameter governs how precisely the decompressor decompresses the image data. Some decompressors may choose to ignore some image data to improve decompression speed. A new accuracy parameter takes effect with the next frame in the sequence.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

SEE ALSO

You set the default accuracy value for a sequence with the accuracy parameter to the DecompressSequenceBegin function.

SetDSequenceDataProc

The SetDSequenceDataProc function lets you assign a data-loading function to the sequence.

pascal OSErr SetDSequenceDataProc (ImageSequence seqID,
                                         ICMDataProcRecordPtr dataProc,
                                         long bufferSize);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
dataProc
Points to a data-loading function structure. If the data stream is not all in memory when your program calls DecompressSequenceFrame , the decompressor calls a function you provide that loads more compressed data (see "Data-Loading Functions," for more information about data-loading functions). If you have not provided a data-loading function, or if you want the decompressor to stop using your data-loading function, set this parameter to nil . In this case, the entire image must be in memory at the location specified by the data parameter to the DecompressSequenceFrame function (see DecompressSequenceFrame ).
bufferSize
Specifies the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

DESCRIPTION

Data-loading functions allow decompressors to work with images that cannot fit in memory. During the decompression operation the decompressor calls the data-loading function whenever it has exhausted its supply of compressed data. Your data-loading function then fills the available buffer space with more compressed data. The decompressor starts using the data-loading function with the next image in the sequence. See "Spooling Compressed Data," which begins on Spooling Compressed Data , for more information about data-loading functions.

There is no parameter to the DecompressSequenceBegin function that allows you to assign a data-loading function to a sequence.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

GetDSequenceImageBuffer

The GetDSequenceImageBuffer function helps you determine the location of the offscreen image buffer allocated by the decompressor.

pascal OSErr GetDSequenceImageBuffer (ImageSequence seqID,
                                          GWorldPtr *gworld);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
gworld
Contains a pointer to a field to receive a pointer to the structure of type GWorld describing the graphics world for the image buffer. If the decompressor has allocated an offscreen image buffer, the decompressor returns an appropriate GWorldPtr in the field referred to by this parameter. If the decompressor has not allocated a buffer, the function returns an error result code.
You should not dispose of this graphics world--the returned pointer refers to a buffer that the Image Compression Manager is using. It is disposed of for you when the CDSequenceEnd function is called. For details on CDSequenceEnd , see CDSequenceEnd .

DESCRIPTION

The decompressor uses this buffer when decompressing a sequence that was temporally compressed. You cause the decompressor to use an image buffer by setting the codecFlagUseImageBuffer flag to 1 in the flags parameter to the DecompressSequenceBegin function.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

GetDSequenceScreenBuffer

The GetDSequenceScreenBuffer function enables you to determine the location of the offscreen buffer allocated by the decompressor.

pascal OSErr GetDSequenceScreenBuffer (ImageSequence seqID,
                                          GWorldPtr *gworld);
seqID
Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on DecompressSequenceBegin ).
gworld
Contains a pointer to a field to receive a pointer to the graphics world structure (defined by the GWorld data type) describing the graphics world for the screen buffer. If the decompressor has allocated an offscreen buffer, the decompressor returns an appropriate GWorldPtr in the field referred to by this parameter. If the decompressor has not allocated a buffer, the function returns an error result code.
You should not dispose of this graphics world--the returned pointer refers to a buffer that the Image Compression Manager is using. It is disposed of for you when the CDSequenceEnd function is called. For details on CDSequenceEnd , see CDSequenceEnd .

DESCRIPTION

The decompressor uses this buffer for decompressed images. During decompression the decompressor writes the decompressed image to an offscreen buffer and then copies the results to the screen. This reduces the tearing effect that can result from decompressing directly to the screen. You cause the decompressor to use a screen buffer by setting the codecFlagUseScreenBuffer flag to 1 in the flags parameter to the DecompressSequenceBegin function.

RESULT CODES

noErr

0

No error

paramErr

-50

Invalid parameter specified

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next